.so ../bk-macros
.TH "bk fmtool" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.\"    =============== BitKeeper 2-way File Merge Tool ===============
.SH NAME
bk fmtool \- \*(BK side-by-side merge tool
.SH SYNOPSIS
.B bk fmtool
.br
.B bk fmtool
.ARG local_file
.ARG remote_file
.ARG merged_file
.SH DESCRIPTION
.LP
.B bk fmtool
is a side-by-side merge tool used for resolving differences
between two different versions of a file.
.LP
If
.B bk fmtool
is started without arguments, use the
.Q Open
button to select the files that you wish to merge.
.LP
When fmtool is started, there are three main windows, the ``local''
window on the left, the ``remote'' window on the right, and the ``merge''
window on the bottom.  When doing a
.BR "bk pull" ,
your repository
is considered local and the other one is considered remote, and \*(BK
arranges to have the local version of the file on the left side and the
remote version on the right.
.LP
Merging is done as follows: 
.LI
.B bk fmtool
starts scanning both files from the top until difference
are found. The identical work (i.e the work up to the point where
the differences are found) is put in the merge window.
.li
The user selects whether the remote or local version of the change
will be used by clicking the
.Q Use Left
or
.Q Use Right
buttons.
When the user picks a version, the changes are placed in the merge
window.
.li
Repeat the process until all changes are placed in the merge file.
.LP
The changes in the merge window are colored so that it is easy to tell whether
the work was from the local or remote file.
.LP
Each merge may be undone either by clicking the
.Q Undo
button or using
the keys listed below.  The undo works all the way to the start of
the file.
.LP
If you need to make adjustments to the merge, you can edit the work in 
the merge window.  The merge window is a simple editor \- move the mouse
pointer where you want to make the changes and start typing.
.SH BINDINGS
.TP \fBControl-Right-Arrow\fP
.B Control-LeftArrow
Use the diff in the left window.
.tp
.B Control-RightArrow
Use the diff in the right window.
.tp
.B Control-DownArrow
Skip the current diff, using neither.
.tp
.B Control-UpArrow
Undo the last choice.
.tp
.B Control-q
Exit from
.BR "bk fmtool" .
.tp
.B Alt-UpArrow
Grow the merge window and shrink the diff windows.
.tp
.B Alt-DownArrow
Grow the diff windows and shrink the merge window.
.LP
The following keys operate on the set of windows that have the focus.
Click in the diff windows or the merge window to set the focus.
.TP \fBControl-Right-Arrow\fP
.B PageDown
Scroll the diffs or the merge window up one screen.
.tp
.B PageUp
Scroll the diffs or the merge window up one screen.
.tp
.B DownArrow
Scroll the diffs or the merge window up one line.
.tp
.B UpArrow
Scroll the diffs or the merge window up one line.
.ig
.LP
Not yet because maybe we should have shift-<key> do the upper windows and
no shift do the lower windows.
.LP
By default, scrolling keys operate on the merge window.
Clicking in the diffs window will shift focus there and make the
scrolling work there.
Clicking in the merge window will shift the focus back.
..
.\" help://GUI-tools/fm
.SH "SEE ALSO"
.SA config-gui
.SA merge
.SA merge-binaries
.SA resolving
.SH CATEGORY
.B GUI-tools
.br
.B File
